home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Games Collection 1 / software vault.zip / software vault / CDR10 / SPX20.ZIP / SPX_DOC.ZIP / SPX_SND.DOC < prev    next >
Text File  |  1993-09-15  |  11KB  |  344 lines
  1. { SPX Library Version 2.0  Copyright 1993 Scott D. Ramsay }
  2.  
  3.   The SPX_SND units it the direct sound unit.   It allows
  4. the playing of digital sound through a Sound Blaster compatible card,
  5. a DAC device on the LPT port (Covox), or the PC speaker.
  6.   It also maintains eight clock timers to use for game precision.
  7.  
  8.      s_clk : array[0..3] of word;  { slow counters }
  9.      f_clk : array[0..3] of word;  { fase counters }
  10.  
  11.   The unit takes control of the computer's clock interrupt and allows
  12. the changing of its interrupt frequency.  From its regular 18.2 times per
  13. second.
  14.  
  15.   The slow counters always count down at 18.2 times a second. Regardless of
  16. the clock interrupt's rate. So, for example, the loop below will wait
  17. for 5 seconds:
  18.  
  19.    s_clk[0] := 5*18;
  20.    repeat
  21.    until s_clk[0]=0;
  22.  
  23.   Notice that there is nothing in the repeat loop.  The counters are
  24. automatically decremented.  The counter also do not roll over. They will
  25. decrement until they reach zero then stop.
  26.  
  27.   The fast counters count down according to the clock rate.  The clock rate
  28. can be changed by the following procedure:
  29.  
  30.     procedure setrate(cycles:word);
  31.  
  32.   The variable cycles indicates the number of cycles(interrupts) to generate
  33. per second.  So  setrate(18);  will restore the clock to its original rate.
  34. Setrate(1000);  will generate an interrupt 1000 times per second.  Warning some
  35. slow computers (8086/286) can not handle high clock rates.  Also conflicts
  36. may occur if running under MS Windows or OS/2.
  37.  
  38.    Here's another example:
  39.  
  40.       setrate(2048);  { set the clock rate }
  41.       f_clk[0] := 4096;
  42.       repeat
  43.       until f_clk[0]=0;
  44.  
  45.    The above example will loop for 2 seconds.
  46.  
  47.    A nice thing about the counters is that you can use them to
  48. regulate the speed of your program/game.  Lets make a VERY rough
  49. example.  Lets suppose you wrote a game that you want each 'frame'
  50. or pass to take 1 second.  Your game loop would look something
  51. like this:
  52.  
  53.      repeat
  54.        s_clk[0] := 18;
  55.        { grab user inputs }
  56.        { do game calcuations }
  57.        { setup objects for display }
  58.        { update visual screen }
  59.        while s_clk[0]<>0 do;
  60.      until game_over;
  61.  
  62.    If one pass of the loop is faster than one second, then the game
  63. will wait in the while loop until a second it up. Now depending on the
  64. speed of the computer, the number of calcuations, speed of displaying the
  65. sprites, the wait time may vary.  But the above loop will always wait
  66. at MOST one second.  Now if one pass takes longer than a second then the
  67. counter is already reached zero so there is no delay.  So the loop is
  68. running at maximum speed.
  69.  
  70.    Now the event loops for games tend to run alot faster than 1 sec.  So
  71. we would use a fast clock counter.
  72.  
  73.      setrate(3000);
  74.      repeat
  75.        f_clk[0] := 80;
  76.        { grab user inputs }
  77.        { do game calcuations }
  78.        { setup objects for display }
  79.        { update visual screen }
  80.        while f_clk[0]<>0 do;
  81.      until game_over;
  82.  
  83.    Now were all set.  We can even get fancy.  We can even automatically
  84. adjust the rate according to the cabilities of the machine;
  85.  
  86.      var
  87.        crate    : word;
  88.  
  89.      setrate(3000);
  90.      crate := 80;
  91.      repeat
  92.        f_clk[0] := crate;
  93.        { grab user inputs }
  94.        { do game calcuations }
  95.        { setup objects for display }
  96.        { update visual screen }
  97.        if (crate>0) and (f_clk[0]<10)
  98.          then dec(crate);
  99.        while f_clk[0]<>0 do;
  100.      until game_over;
  101.  
  102.    Now if the computer can't keep up with the rate (The clock comes
  103. close to timing out).  The rate is speeded up.
  104.  
  105.  
  106.    The unit uses the variable clock speeds for the playing of
  107. the audio.  To play an audio segment, the unit sets the clock rate
  108. to the sample rate of the sound.  Then at each interrupt it outputs
  109. a sample byte to directed sound port.
  110.  
  111.    Here are some ports you can use.
  112.  
  113.      $42        -  PC speaker
  114.      $378       -  LPT1 sound devices such as Covox
  115.      $210-$260  -  Sound Blaster compatible cards
  116.  
  117.    Here's how to play an 8khz raw sound file:
  118.  
  119.      Uses SPX_SND;
  120.  
  121.      var
  122.         sound : Tsound;
  123.      begin
  124.        setrate(8192);                        { Set clock to sound sample }
  125.        sound.init('Mysound.raw',$42,false);  { load the sound, use PC speaker }
  126.        sound.play(true);                     { play the sound }
  127.        repeat until not playing;             { wait for completion }
  128.        sound.done;                           { do cleanup }
  129.      end.
  130.  
  131.  
  132. NOTES:
  133.       This unit will not work in protected mode because of changing the clock
  134. rate.  As a result the the f_clk counters will act as s_clk counters.  Such
  135. in a Windows DOS box. etc.
  136. ───────────────────────────────────────────────────────────────────────────
  137. GLOBAL VARIABLES:
  138.  
  139.       cs:        Can stop flag, FALSE - if the current audio playing
  140.                  does not want to be interupted
  141.       playing:   TRUE - if a sound is currently playing
  142.       f_clk:     Fast clock counters
  143.       s_clk:     Slow clock counters
  144.       rate:      Current fast clock rate
  145.       cntime:    Reserved counter, Do not modify
  146.   --------------------------------------------------------
  147.       f_userclk,
  148.       s_userclk   : userproc;
  149.  
  150.     F_USERCLK and S_USERCLK allows you to add your own custom routines
  151.   at each clock interrupt.  Since these procedures are called at every
  152.   interrupt you have to avoid a few things:
  153.  
  154.       1.  You routine should be fast as possible. Since it will be called
  155.          many times.  if it does to many calculations, it will slow the
  156.          program down.
  157.  
  158.       2. Do not call any interupts.  You are already in one.
  159.  
  160.       3. Avoid disk access.  It may or may not work.  Don't try it!
  161.  
  162.       4. Your routine must be declared as a far procedure with no
  163.          parameters.
  164.  
  165.   Example:
  166.  
  167.     Uses spx_tim;
  168.  
  169.     var
  170.       l,s : longint;
  171.  
  172.     procedure MyUserClk;  far;
  173.     begin
  174.       inc(l);
  175.     end;
  176.  
  177.  
  178.     begin
  179.       l := 0;
  180.       s_userclk := MyUserClk;
  181.       readln; s := l;
  182.       writeln('My function was called ',s,' times while waiting');
  183.     end.
  184.  
  185.  
  186. ───────────────────────────────────────────────────────────────────────────
  187. type
  188.   Psound    = ^Tsound;
  189.   Tsound    = object
  190.  
  191.   Base sound object.  Used for playing digitized sound.
  192.  
  193. VARIABLES:
  194.         sblk:pointer     Buffer to the sound data;
  195.         size:word        Size of sound buffer;
  196.         sport:word       Port address for sound;
  197.         sb_play:boolean  Set to TRUE if (sport) is a sound blaster
  198.                          port
  199.  
  200. METHODS:
  201.  
  202.    ---------------------------------------------------
  203.    constructor tsound.init(sndfile:string;prt:word;_sb:boolean);
  204.  
  205.    Sets up the sound object.  By loading the the sound file
  206.  
  207.     SNDFILE:  DOS file name of raw sound file;
  208.     PRT:      Sound port to use for the object;
  209.     _SB:      Set to TRUE if PRT is a sound blaster port
  210.  
  211.  
  212.    ---------------------------------------------------
  213.    function tsound.loadsnd(sndfile:string;prt:word;_sb:boolean):boolean; virtual;
  214.  
  215.    Load a raw sound file into the object.
  216.  
  217.    SNDFILE: DOS file name of the raw sound file;
  218.    PRT:     Sound port to use for the object;
  219.    _SB:     Set to TRUE if PRT is a Sound Blaster port
  220.  
  221.    ---------------------------------------------------
  222.    function tsound.filesnd(var fil:file;bsize,prt:word;_sb:boolean):boolean; virtual;
  223.  
  224.    Loads a data from an open file.
  225.  
  226.    FIL:    File that contains sound data;
  227.    BSIZE:  Size of sound data in file;
  228.    PRT:    Sound port to use for the object;
  229.    _SB:    Set to TRUE if PRT is a Sound Blaster port
  230.  
  231.    NOTE: Does not close file
  232.  
  233.    ---------------------------------------------------
  234.    procedure tsound.cleansnd; virtual;
  235.  
  236.    Deallocates heap memory space for the sound.
  237.  
  238.    ---------------------------------------------------
  239.    procedure tsound.play(canstop:boolean); virtual;
  240.  
  241.    Plays the sound.
  242.  
  243.      CANSTOP:  Set to TRUE is allow other sounds to
  244.        interrupt its playing.
  245.  
  246.    ---------------------------------------------------
  247.    procedure tsound.stop; virtual;
  248.  
  249.    Stop the playing of the sound.
  250.  
  251.    ---------------------------------------------------
  252.    destructor tsound.done; virtual;
  253.  
  254.    Preforms and deallocation of the object;
  255.  
  256. ───────────────────────────────────────────────────────────────────────────
  257. type
  258.   PEmsSound = ^TEmsSound;
  259.   TEmsSound = object(Tsound)
  260.  
  261.   Expanded memory sound object.  Used for playing digitized sound.  Stores
  262.   the sound in expanded memory.
  263.  
  264. VARIABLES:
  265.  
  266.       EMSseg:     Segment address of EMS window
  267.       handle:     Handle to the ems memory block
  268.       EMSok:      Status of the EMS block, TRUE if okay
  269.  
  270. METHODS:
  271.  
  272.    ---------------------------------------------------
  273.    constructor TEmsSound.init(sndfile:string;prt:word;_sb:boolean);
  274.  
  275.    Sets up the sound object.  By loading the the sound file
  276.  
  277.     SNDFILE:  DOS file name of raw sound file;
  278.     PRT:      Sound port to use for the object;
  279.     _SB:      Set to TRUE if PRT is a sound blaster port
  280.  
  281.     ---------------------------------------------------
  282.     function TEmsSound.loadsnd(sndfile:string;prt:word;_sb:boolean):boolean; virtual;
  283.  
  284.     Load a raw sound file into the object.
  285.  
  286.     SNDFILE: DOS file name of the raw sound file;
  287.     PRT:     Sound port to use for the object;
  288.     _SB:     Set to TRUE if PRT is a Sound Blaster port
  289.  
  290.     ---------------------------------------------------
  291.     procedure TEmsSound.cleansnd; virtual;
  292.  
  293.     Deallocates expanded memory space for the sound.
  294.  
  295.     ---------------------------------------------------
  296.     procedure TEmsSound.play(canstop:boolean); virtual;
  297.  
  298.     Plays the sound.
  299.  
  300.      CANSTOP:  Set to TRUE is allow other sounds to
  301.        interrupt its playing.
  302.  
  303.     ---------------------------------------------------
  304.     destructor TEmsSound.done; virtual;
  305.  
  306.     Preforms and deallocation of the object.
  307.  
  308. ───────────────────────────────────────────────────────────────────────────
  309. function SBFindBase:word;
  310.  
  311.   Searches for a Sound Blaster compatible card.  If found, returns the port
  312.   address of the card. Returns 0 if not found.
  313.  
  314. ───────────────────────────────────────────────────────────────────────────
  315. function SBReset(BaseAddr : word) : boolean;
  316.  
  317.   Resets the sound card.  Returns TRUE if successful.
  318.  
  319.   BASEADDR:  Port address of sound card
  320.  
  321. ───────────────────────────────────────────────────────────────────────────
  322. procedure globalstop;
  323.  
  324.   Stops playback of sound.
  325.  
  326.   Note: Same as Tsound.stop and TEmsSound.stop
  327.  
  328. ───────────────────────────────────────────────────────────────────────────
  329. procedure setrate(cycles:word);
  330.  
  331.   Changes the clock rate of the computer.
  332.  
  333.   CYCLES:  Number of interrupts to generate per second
  334.  
  335. ───────────────────────────────────────────────────────────────────────────
  336. procedure wait(seconds,which:integer);
  337.  
  338.   Wait for a specified number of seconds.
  339.  
  340.   SECONDS:  Number of seconds to wait;
  341.   WHICH:    Index number of slow clock counter to use.  (0..3)
  342.  
  343. ───────────────────────────────────────────────────────────────────────────
  344.